<HTML>
<HEAD>
<TITLE> SUBPT User's Guide </TITLE>
</HEAD>

<BODY style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">

<A NAME="top"></A>

<TABLE STYLE="text-align: left; margin-left: auto; margin-right: auto; width: 800px;" BORDER="0" CELLPADDING="5" CELLSPACING="2">
<TBODY>
<TR>
  <TD STYLE="background-color: rgb(153, 153, 153); vertical-align: middle; text-align: center;">
  <DIV ALIGN="right">
    <SMALL><SMALL><A HREF="index.html">Index Page</A></SMALL></SMALL>
  </DIV>
  <B>SUBPT User's Guide</B> </TD>
</TR>
<TR>
  <TD STYLE="vertical-align: top;">

<H2> Table of Contents
</H2>

<PRE>
   <A HREF="#SUBPT User's Guide">SUBPT User's Guide</A>
      <A HREF="#Abstract">Abstract</A>
      <A HREF="#Summary">Summary</A>

</PRE>

<HR SIZE=3 NOSHADE>

<BR><BR>
<A NAME="SUBPT User's Guide"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> SUBPT User's Guide
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   Last revised on 2008 FEB 07 by N. J. Bachman.
<P>
 
<BR><BR>
<A NAME="Abstract"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Abstract
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   SUBPT is a cookbook program that demonstrates how to use CSPICE Toolkit
   routines to compute a sub-observer point.
<P>
 
<BR><BR>
<A NAME="Summary"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Summary
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The SUBPT ``cookbook'' program illustrates the use of CSPICE Toolkit
   software for solving a typical geometrical problem --- computing the
   apparent sub-observer point on a target body using light time and
   stellar aberration corrections.
<P>
 
   The ``apparent sub-observer point'' is defined in this program to be the
   point on the target body that appears to be closest to the observer. The
   apparent sub-observer point may also be defined as the intercept on the
   target's surface of the ray emanating from the observer and passing
   through the apparent target body's center, but we don't demonstrate use
   of that definition here. See the header of the function <a href="../cspice/subpnt_c.html">subpnt_c</a> for
   details.
<P>
 
   In order to compute the apparent location of the sub-observer point, we
   correct the position of the sub-observer point for both light time and
   stellar aberration, and we correct the orientation of the target body
   for light time. We consider ``light time'' to be the time it takes a
   photon to travel from the sub-observer point to the observer. If the
   light time is given the name LT, then the apparent position of the
   sub-observer point relative to the observer is defined by the vector
   from the sub-observer point's location (relative to the solar system
   barycenter) at ET-LT, minus the observer's location (again, relative to
   the solar system barycenter) at ET, where this difference vector is
   corrected for stellar aberration.
<P>
 
   See the header of the CSPICE function <a href="../cspice/spkezr_c.html">spkezr_c</a> for more information on
   light time and stellar aberration corrections; see the header of the
   CSPICE routine <a href="../cspice/subpnt_c.html">subpnt_c</a> for an explanation of how it applies aberration
   corrections.
<P>
 
   SUBPT demonstrates the use of the following high-level CSPICE functions:
<P>
 
<DL><DT>
<B>
 <a href="../cspice/prompt_c.html">prompt_c</a>
</B><BR><BR>
<DD>
 Interactively prompt user for a string input<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/furnsh_c.html">furnsh_c</a>
</B><BR><BR>
<DD>
 Load SPICE kernels<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/str2et_c.html">str2et_c</a>
</B><BR><BR>
<DD>
 Convert time string to ephemeris time<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/subpnt_c.html">subpnt_c</a>
</B><BR><BR>
<DD>
 Calculate the sub-point<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/et2utc_c.html">et2utc_c</a>
</B><BR><BR>
<DD>
 Convert ephemeris time to UTC string<BR>
</DL>
   To run SUBPT, you need a binary SPK ephemeris file and knowledge of the
   bodies and the corresponding time intervals contained in that file. The
   utility program named BRIEF summarizes the contents and time coverage of
   a binary SPK file. Refer to NAIF IDs Required Reading (<a href="../req/naif_ids.html">naif_ids.req</a>) for
   a list of body names and integer codes. In addition to an SPK file, you
   also require access to leapsecond (LSK) and planetary constants (PCK)
   kernels.
<P>
 
   SUBPT prompts you for the NAIF IDs or string name of a target body and
   observing body, the name of the body-fixed reference frame associated
   with the target body, the UTC end-points of a time interval, and the
   number of evaluations to perform over the assigned time interval. The
   program then computes the planetocentric coordinates of the apparent
   sub-observer point on the target body, printing to the terminal screen
   for each time in the interval.
<P>
 
   Below, find a sample session using SUBPT to calculate the latitude and
   longitude of the nearest point on the Earth to the Sun through a single
   day. SUBPT can be used with any SPK file containing appropriate data.
<P>
 
   Please note: FORTRAN and C versions of the program can output numerical
   values in slightly different formats.
<P>
 
   It is assumed the kernel files used by SUBPT exist in the current
   directory (i.e. the directory from which your execute SUBPT). This
   particular session was run on an Intel box using the LINUX operating
   system.
<P>
 
   First, create the binary SPK kernel cook_01.bsp by running the CSPICE
   Toolkit TOBIN application on the transfer format file cook_01.tsp
   located in the CSPICE data directory. The program also requires a
   leapseconds kernel to run; an example leapseconds kernel, cook_01.tls
   exists within the same directory. Now, execute SUBPT:
<P>
 
<PRE>
 
                Welcome to SUBPT
 
   This program demonstrates the use of CSPICE in computing
   the apparent sub-observer point on a target body. The
   computations use light time and stellar aberration
   corrections.
 
   Enter the name of leapseconds kernel file: cook_01.tls
 
   Enter the name of a planetary constants kernel: cook_01.tpc
 
   Enter the name of a binary SPK file: cook_01.bsp
 
   Working ... Please wait.
 
   Enter the name for the observing body: sun
 
   Enter the name for a target body: earth
 
   Enter the name of the target body-fixed frame: iau_earth
 
   Enter the number of points to calculate: 24
 
   Enter the beginning UTC time: jul 1 1990
 
   Enter the ending UTC time: jul 2 1990
 
   Planetocentric coordinates for the nearest point
   on the target body to the observing body (deg).
   Target body: earth          Observing body: sun
 
          UTC Time            Lat         Lon
   ----------------------------------------------
     1990 JUL 01 00:00:00   23.00157    -176.92004
     1990 JUL 01 01:02:36   22.99879    167.42991
     1990 JUL 01 02:05:13   22.99600    151.77986
     1990 JUL 01 03:07:49   22.99320    136.12981
     1990 JUL 01 04:10:26   22.99039    120.47976
     1990 JUL 01 05:13:02   22.98757    104.82970
     1990 JUL 01 06:15:39   22.98473     89.17964
     1990 JUL 01 07:18:15   22.98188     73.52958
     1990 JUL 01 08:20:52   22.97902     57.87952
     1990 JUL 01 09:23:28   22.97614     42.22946
     1990 JUL 01 10:26:05   22.97325     26.57939
     1990 JUL 01 11:28:41   22.97035     10.92932
     1990 JUL 01 12:31:18   22.96744     -4.72075
     1990 JUL 01 13:33:54   22.96451    -20.37082
     1990 JUL 01 14:36:31   22.96157    -36.02090
     1990 JUL 01 15:39:07   22.95862    -51.67097
     1990 JUL 01 16:41:44   22.95566    -67.32105
     1990 JUL 01 17:44:20   22.95268    -82.97114
     1990 JUL 01 18:46:57   22.94969    -98.62122
     1990 JUL 01 19:49:33   22.94669    -114.27131
     1990 JUL 01 20:52:10   22.94368    -129.92140
     1990 JUL 01 21:54:46   22.94065    -145.57149
     1990 JUL 01 22:57:23   22.93761    -161.22158
     1990 JUL 02 00:00:00   22.93456    -176.87168
 
   Continue? (Enter Y or N): N
</PRE>

</TD>
</TR>
</TBODY>
</TABLE>

</BODY>

</HTML>
